home *** CD-ROM | disk | FTP | other *** search
/ Aminet 49 / Aminet 49 (2002)(GTI - Schatztruhe)[!][Jun 2002].iso / Aminet / util / libs / ttrender.lha / ttrender-2.0 / Developer / autodocs / ttrender.doc
Encoding:
Text File  |  2002-04-06  |  13.5 KB  |  438 lines
  1. TABLE OF CONTENTS
  2.  
  3. ttrender.library/background
  4. ttrender.library/TT_GetFontAttrsTagList
  5. ttrender.library/TT_PutStr
  6. ttrender.library/TT_PutStrTagList
  7. ttrender.library/TT_PutUStr
  8. ttrender.library/TT_PutUStrTagList
  9. ttrender.library/TT_SetFont
  10. ttrender.library/TT_SetModesTagList
  11. ttrender.library/TT_StrWidth
  12. ttrender.library/TT_UStrWidth
  13. ttrender.library/background                       ttrender.library/background
  14.  
  15.  
  16.    PURPOSE
  17.  
  18.    The library is fast, AmigaOS friendly TrueType render engine. It has
  19.    nothing to do with Amiga outline font system. This system has a lot of
  20.    limitations which make it useless for high speed and quality text output.
  21.    If someone wants an integration of TrueType with AmigaOS bullet.library
  22.    like outline font system, should consider using ttf.library. This library
  23.    opens TrueType font by itself and renders high quality glyphs directly
  24.    into any RastPort.
  25.  
  26.    FREETYPE2 BASED
  27.  
  28.    The render engine of the library is based on FreeType2 project
  29.    (http://www.freetype.org). This version of ttrender.library uses 2.0.9
  30.    FreeType build.
  31.  
  32.    REQUIREMENTS
  33.  
  34.    The library requires at least CyberGraphX 3.x or Picasso96 2.x system. It
  35.    is possible that non-antialiased output will be possible on AGA machines
  36.    in the future.
  37.  
  38.    FEATURES
  39.  
  40.    The library expands FreeType functionality making usage of TrueType fonts
  41.    easy and comfortable. Below you can find key features:
  42.  
  43.    - renders whole strings (not single glyphs) with kerning.
  44.    - antialiasing to any (not neccesarily uniform color) background.
  45.    - system compatible output to any (including planar) RastPort.
  46.    - supports JAM1. JAM2, INVERSVID, COMPLEMENT RastPort modes.
  47.    - supports 8-bit to Unicode mapping with "ENV:ttfcodepage" table
  48.      compatible with ttf.library.
  49.    - allows for direct 16-bit Unicode string rendering.
  50.    - easy to use, taglist based API.
  51.    - efficient system-wide glyph cache system.
  52.  
  53.    CACHE SYSTEM
  54.  
  55.    The library uses my own (not that experimental FreeType one) cache system
  56.    speeding up strings rendering alot. The cache is system-wide, it means it
  57.    is common to every application using ttrender.library. Only used glyphs of
  58.    given font face are cached. If the library encounters cache miss, missing
  59.    glyph is loaded and rasterized on the fly. Cache system is totally
  60.    transparent to the library user, so there are no cache functions in the
  61.    library API. Cache uses one single Exec memory pool avoiding memory
  62.    fragmentation.
  63.  
  64.    FONT DIRECTORIES
  65.  
  66.    The library searches for a font in three directories:
  67.    1. Process current directory.
  68.    2. "PROGDIR:" of the calling application.
  69.    3. "FONTS:_TrueType_Outlines" as a common location for TrueType fonts.
  70.  
  71. ttrender.library/TT_GetFontAttrsTagListtrender.library/TT_GetFontAttrsTagList
  72.  
  73.    NAME
  74.        TT_GetFontAttrsTagList -- Gets current font attributes (V2).
  75.  
  76.    SYNOPSIS
  77.        count = TT_GetFontAttrsTagList (taglist)
  78.                                        A0
  79.  
  80.        ULONG TT_GetFontAttrsTagList (struct TagItem*);
  81.  
  82.        count = TT_GetFontAttrsTags (Tag1, ...)
  83.  
  84.        ULONG TT_GetFontAttrsTags (Tag, ...);
  85.  
  86.    FUNCTION
  87.        Gets current (set by last SetFont() call) font attributes (global
  88.        metrics mainly). The value of every attribute is written to an ULONG
  89.        pointed by ti_Data field of the TagItem. Here is a list of attributes:
  90.  
  91.        TTFA_Ascender - This is a distance (in pixels) between the baseline
  92.          and top elements of the font (typically these elements are accents
  93.          of capital letters). NOTE: many shareware TT fonts have wrong ascen-
  94.          der value.
  95.  
  96.        TTFA_Descender - This is a distance (in pixels) between the baseline
  97.          and bottom elements of the font (typically in letters 'p', 'q', 'g'
  98.          etc.). NOTE: many shareware TT fonts have wrong descender value.
  99.          Descender value is typically negative (as bottom elements usually
  100.          are placed below the baseline).
  101.  
  102.        NOTE: TTFA_Ascender and TTFA_Descender are guarranted to fulfill
  103.        following formula: ascender - descender = font height.
  104.  
  105.    INPUTS
  106.        taglist - the list of attributes.
  107.  
  108.    RESULT
  109.        counter - the count of recognized tags.
  110.  
  111.    NOTES
  112.  
  113.    BUGS
  114.  
  115.    SEE ALSO
  116.        TT_SetFont()
  117.  
  118. ttrender.library/TT_PutStr                         ttrender.library/TT_PutStr
  119.  
  120.    NAME
  121.        TT_PutStr -- Renders string into RastPort.
  122.  
  123.    SYNOPSIS
  124.        success = TT_PutStr (string)
  125.                             A0
  126.  
  127.        BOOL TT_PutStr (UBYTE*);
  128.  
  129.    FUNCTION
  130.        Renders the string using current ttrender.library settings, and
  131.        current RastPort settings (pen, drawmode). String is rendered at
  132.        current RastPort (x, y) position, where 'y' means position of font
  133.        baseline. String is converted to Unicode according to
  134.        "ENV:ttfcodepage" mapping table. If there is no mapping table,
  135.        ISO-8859-1 mapping is used which is equal to ECMA Latin1 Amiga
  136.        standard.
  137.  
  138.    INPUTS
  139.        string - NULL-terminated string to render to.
  140.  
  141.    RESULT
  142.        TRUE if the string has been rendered.
  143.  
  144.    EXAMPLE
  145.        /* write a text with pen 1 and transp. background at (100, 100) */
  146.        /* rendering is done to a system window                         */
  147.  
  148.        SetAPen(win->RPort, 1);
  149.        SetDrMd(win->RPort, JAM1);
  150.        Move(win->RPort, 100, 100);
  151.        TT_SetModesTags(TTA_Window, win);
  152.        TT_PutStr("some text");
  153.  
  154.    NOTES
  155.  
  156.    BUGS
  157.  
  158.    SEE ALSO
  159.        TT_PutStrTagList(), TT_SetModesTagList(), TT_PutUStr()
  160.  
  161. ttrender.library/TT_PutStrTagList           ttrender.library/TT_PutStrTagList
  162.  
  163.    NAME
  164.        TT_PutStrTagList -- Renders string into RastPort with local settings.
  165.  
  166.    SYNOPSIS
  167.        success = TT_PutStrTagList (string, taglist)
  168.                                    A0      A1
  169.  
  170.        BOOL TT_PutStrTagList (UBYTE*, struct TagItem*);
  171.  
  172.        success = TT_PutStrTags (string, Tag1, ...)
  173.  
  174.        BOOL TT_PutStrTags (UBYTE*, Tag, ...);
  175.  
  176.    FUNCTION
  177.        Renders the string allowing temporary override of current
  178.        ttrender.library settings, and current RastPort settings. Attributes
  179.        given in the taglist have local precedence over global
  180.        ttrender.library settings set by TT_SetModesTagList() call. Check
  181.        TT_SetModesTagList() docs for a list of tags.
  182.  
  183.    INPUTS
  184.        string - NULL-terminated string to render to.
  185.  
  186.        taglist - local attributes valid only in this function call.
  187.  
  188.    RESULT
  189.        TRUE if the string has been rendered.
  190.  
  191.    EXAMPLE
  192.  
  193.        /* Turn antialias mode on globally */
  194.  
  195.        TT_SetModesTags(TTA_Antialias, TRUE);
  196.  
  197.        TT_PutStr("some text");           /* this text will be antialiased */
  198.        TT_PutStrTags("another text",
  199.          TTA_Antialias, FALSE,           /* this text won't (locally      */
  200.          TAG_END);                       /* switched off)                 */
  201.        TT_PutStr("third text");          /* this text will be antialiased */
  202.  
  203.    NOTES
  204.  
  205.    BUGS
  206.  
  207.    SEE ALSO
  208.        TT_PutStr(), TT_SetModesTagList()
  209.  
  210. ttrender.library/TT_PutUStr                       ttrender.library/TT_PutUStr
  211.  
  212.    NAME
  213.        TT_PutUStr -- Renders Unicode string into RastPort.
  214.  
  215.    SYNOPSIS
  216.        success = TT_PutUStr (string)
  217.                              A0
  218.  
  219.        BOOL TT_PutUStr (UWORD*);
  220.  
  221.    FUNCTION
  222.        Renders the string using current ttrender.library (RastPort, ColorMap,
  223.        render mode), and RastPort settings (pen, drawmode). String is
  224.        rendered at current RastPort (x, y) position, where 'y' means position
  225.        of font baseline. String is an 16-bit Unicode one and should be
  226.        terminated with 16-bit zero.
  227.  
  228.    INPUTS
  229.        string - 16-bit Unicode NULL-terminated string to render to.
  230.  
  231.    RESULT
  232.        TRUE if the string has been rendered.
  233.  
  234.    BUGS
  235.  
  236.    SEE ALSO
  237.        TT_PutUStrTagList(), TT_SetModesTagList(), TT_PutStr()
  238.  
  239. ttrender.library/TT_PutUStrTagList         ttrender.library/TT_PutUStrTagList
  240.  
  241.    NAME
  242.        TT_PutUStrTagList -- Renders 16-bit Unicode string into RastPort with
  243.                            local settings.
  244.  
  245.    SYNOPSIS
  246.        success = TT_PutUStrTagList (string, taglist)
  247.                                    A0      A1
  248.  
  249.        BOOL TT_PutUStrTagList (UWORD*, struct TagItem*);
  250.  
  251.        success = TT_PutUStrTags (string, Tag1, ...)
  252.  
  253.        BOOL TT_PutUStrTags (UWORD*, Tag, ...);
  254.  
  255.    FUNCTION
  256.        Renders the 16-bit Unicode string allowing temporary override of
  257.        current ttrender.library settings, and current RastPort settings.
  258.        Attributes given in the taglist have local precedence over global
  259.        ttrender.library settings set by TT_SetModesTagList() call. Check
  260.        TT_SetModesTagList() docs for a list of tags.
  261.  
  262.    INPUTS
  263.        string - NULL-terminated 16-bit Unicode string to render to.
  264.  
  265.        taglist - local attributes valid only in this function call.
  266.  
  267.    RESULT
  268.        TRUE if the string has been rendered.
  269.  
  270.    NOTES
  271.  
  272.    BUGS
  273.  
  274.    SEE ALSO
  275.        TT_PutUStr(), TT_SetModesTagList()
  276.  
  277. ttrender.library/TT_SetFont                       ttrender.library/TT_SetFont
  278.  
  279.    NAME
  280.        TT_SetFont -- Opens TrueType font with given name and size.
  281.  
  282.    SYNOPSIS
  283.        success = TT_SetFont (name, size)
  284.                              A0    D0:16
  285.  
  286.        BOOL TT_SetFont (STRPTR, UWORD);
  287.  
  288.    FUNCTION
  289.        Opens TrueType font file and sets current font size in pixels. Every
  290.        following call to TT_PutStr[Tags/TagList]() or
  291.        TT_PutUStr[Tags/TagList]() will use this font and size.
  292.  
  293.    INPUTS
  294.        name - pointer to a NULL terminated string containing font name.
  295.               ".ttf" suffix will be added automatically. Search order is
  296.               defined as follows:
  297.               1. current directory
  298.                   "<name>.ttf"
  299.               2. PROGDIR:
  300.                   "PROGDIR:<name>.ttf"
  301.               3. "FONTS:_TrueType_Outlines" (by analogy to _Bullet_Outlines)
  302.                   "FONTS:_TrueType_Outlines/<name>.ttf"
  303.        size - screen size of the font in pixels (to be exact - it is the
  304.               distance between baselines of two following lines of text
  305.               expressed in pixels).
  306.  
  307.    RESULT
  308.        success - TRUE if the font has been opened successfully, FALSE
  309.                  otherwise. This function can fail for three reasons:
  310.                  1. File not found or malformed.
  311.                  2. Zero font size.
  312.                  3. No memory for requested (too big?) size.
  313.  
  314.    NOTES
  315.  
  316.    BUGS
  317.  
  318.    SEE ALSO
  319.        TT_PutStr(), TT_PutUStr()
  320.  
  321. ttrender.library/TT_SetModesTagList       ttrender.library/TT_SetModesTagList
  322.  
  323.    NAME
  324.        TT_SetModesTagList -- Sets global rendering settings.
  325.  
  326.    SYNOPSIS
  327.        count = TT_SetModesTagList (taglist)
  328.                                    A0
  329.  
  330.        ULONG TT_SetModesTagList (struct TagItem*);
  331.  
  332.        count = TT_SetModesTags (Tag1, ...)
  333.  
  334.        ULONG TT_SetModesTags (Tag, ...);
  335.  
  336.    FUNCTION
  337.        Sets global (per library opening) render engine settings. Every
  338.        following TT_PutStr() / TT_PutUStr() call will use these settings.
  339.        They can by overriden temporarily however, with TT_PutStrTagList() /
  340.        TT_PutUStrTagList() calls. Here is a list of attributes:
  341.  
  342.        TTA_RastPort - (struct RastPort*) - Destination RastPort for
  343.          rendering. The library will adhere to this RastPort settings like
  344.          draw mode, pens, current pen position.
  345.  
  346.        TTA_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
  347.          number to RGB color value.
  348.  
  349.        TTA_Screen - (struct Screen*) - useful shortcut for TTA_RastPort and
  350.          TTA_ColorMap, automatically sets screen ColorMap and screen
  351.          RastPort.
  352.  
  353.        TTA_Window - (struct Window*) - useful shortcut for TTA_RastPort and
  354.          TTA_ColorMap, automatically sets window ColorMap and window
  355.          RastPort.
  356.  
  357.        TTA_Antialias - (BOOL) - controls antialiasing (on or off).
  358.  
  359.    INPUTS
  360.        taglist - the list of global attributes.
  361.  
  362.    RESULT
  363.        counter - the count of recognized tags.
  364.  
  365.    NOTES
  366.        TTA_RastPort and TTA_ColorMap attributes have precedence over
  367.        TTA_Screen and TTA_Window ones. It can be useful if one wants to use
  368.        window/screen ColorMap but separate RastPort. An example:
  369.  
  370.        TT_SetModesTags(TTA_Window, win, TTA_RastPort, my_rport, TAG_END);
  371.  
  372.        It will set window colormap and 'my_rport' as targets. Note that the
  373.        precedence is based on tag values, not on tags order. So ordering of
  374.        the tags is meaningless for the function.
  375.  
  376.    BUGS
  377.  
  378.    SEE ALSO
  379.        TT_PutStr(), TT_SetModesTagList()
  380.  
  381. ttrender.library/TT_StrWidth                     ttrender.library/TT_StrWidth
  382.  
  383.    NAME
  384.        TT_StrWidth -- Gets string width in pixels (V2).
  385.  
  386.    SYNOPSIS
  387.        width = TT_StrWidth(string)
  388.                            A0
  389.  
  390.        ULONG TT_StrWidth (UBYTE*);
  391.  
  392.    FUNCTION
  393.        Calculates the pixel width of given string written with current font.
  394.        Takes kerning into account. String will be mapped to Unicode using
  395.        "ENV:ttfcodepage" table (see TT_PutStr() docs).
  396.  
  397.    INPUTS
  398.        string - the width of this string will be calculated.
  399.  
  400.    RESULT
  401.        width - the width of the string in pixels.
  402.  
  403.    NOTES
  404.  
  405.    BUGS
  406.  
  407.    SEE ALSO
  408.        TT_PutStr(), TT_SetFont()
  409.  
  410. ttrender.library/TT_UStrWidth                   ttrender.library/TT_UStrWidth
  411.  
  412.    NAME
  413.        TT_UStrWidth -- Gets Unicode 16-bit string width in pixels (V2).
  414.  
  415.    SYNOPSIS
  416.        width = TT_UStrWidth(string)
  417.                             A0
  418.  
  419.        ULONG TT_UStrWidth (UWORD*);
  420.  
  421.    FUNCTION
  422.        Calculates the pixel width of given 16-bit Unicode string written
  423.        with current font. Takes kerning into account.
  424.  
  425.    INPUTS
  426.        string - the width of this 16-bit Unicode string will be calculated.
  427.  
  428.    RESULT
  429.        width - the width of the string in pixels.
  430.  
  431.    NOTES
  432.  
  433.    BUGS
  434.  
  435.    SEE ALSO
  436.        TT_PutUStr(), TT_SetFont()
  437.  
  438.